-
Notifications
You must be signed in to change notification settings - Fork 121
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Keccak1600_Squeeze/Absorb Layer (rename) #2097
Merged
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Clean redefinition of SHAKE blocksize/rate macros; Update their use inside MLKEM and MLDSA.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2097 +/- ##
=======================================
Coverage 78.74% 78.75%
=======================================
Files 598 598
Lines 103656 103656
Branches 14720 14720
=======================================
+ Hits 81622 81632 +10
+ Misses 21382 21373 -9
+ Partials 652 651 -1 ☔ View full report in Codecov by Sentry. |
jakemas
reviewed
Jan 6, 2025
@@ -64,11 +64,9 @@ extern "C" { | |||
// SHAKE constants, from NIST FIPS202. | |||
// https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf | |||
#define SHAKE_PAD_CHAR 0x1F | |||
#define SHAKE128_BLOCKSIZE (KECCAK1600_WIDTH - 128 * 2) / 8 | |||
#define SHAKE256_BLOCKSIZE (KECCAK1600_WIDTH - 256 * 2) / 8 | |||
#define SHAKE128_RATE 168 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you for cleaning these (SHAKE128/256_RATE
) up!
jakemas
reviewed
Jan 7, 2025
jakemas
reviewed
Jan 7, 2025
jakemas
reviewed
Jan 7, 2025
Fix alignment Co-authored-by: Jake Massimo <[email protected]>
geedo0
reviewed
Jan 7, 2025
geedo0
approved these changes
Jan 7, 2025
jakemas
approved these changes
Jan 7, 2025
andrewhop
approved these changes
Jan 7, 2025
This was referenced Jan 7, 2025
justsmth
added a commit
that referenced
this pull request
Feb 5, 2025
### Issues: Resolves #CryptoAlg-2810 ### Description of changes: AWS-LC supports SHA3 and SHAKE algorithms though low level SHA3_Init, SHA3_Update, SHA3_Final and SHAKE_init, SHAKE_Final APIs. Currently, there are two issues with the implementation and usage of SHA3 and SHAKE: - There is no support for SHAKE_Update function. SHAKE is implemented by calling SHAKE_Init, SHA3_Update and SHAKE_Final. - SHAKE_Final allows multiple consecutive calls to enable incremental XOF output generation. This PR addresses both of them as follows: - Introduce new API layers - FIPS202, SHA3 and SHAKE. - _Keccak1600_ layer (#2097) implements KeccakF1600 Absorb and Squeeze functions; Keccak1600 layer does _not_ manage internal input/output buffers. - _FIPS202_ layer implements Reset, Init, Update, and Finalize functionalities; FIPS202 layer manages the internal input/output buffers, allowing incremental requests (not necessarily multiple of block size) to Update (Absorb) and Squeeze for input/output processing. (Other functionalities, such as zero-ing of bitstate, block size checks, etc. are also handled by FIPS202 API layer). - _FIPS202_ layer implements all common behavior between SHA3 and SHAKE algorithms. - _FIPS202_ layer checks/updates the |ctx->state| flag when handling a common behavior between SHA3 and SHAKE algorithms. |ctx->state| is updated in the higher level SHA3_ SHAKE_ API layer when the behavior of both algorithms diverges (SHAKE _can_ allow incremental squeezes). - _SHA3_ layer implements Init, Update, and Final functionalities; SHA3 layer only implements SHA3 algorithm, thus, offers a single-call SHA3_Final function. SHA3_Final will update internal |ctx->state| flag to prevent any sequential calls. - _SHAKE_ layer implements XOF SHAKE algorithm, therefore, offers Init, Absorb, Squeeze, and Final functionalities; - _SHAKE_ layer implements Init, and Absorb, Squeeze with incremental call support for absorb (byte-wise) and squeeze (block-wise). - _SHAKE_ layer implements a single-call SHAKE_Final function that generates an arbitrary length output and finalizes SHAKE. Incremental XOF output generation is handled by |SHAKE_Squeeze|. |SHAKE_Squeeze| can be called multiple times. SHAKE_Final should be called only once. - KECCAK600_CTX struct updates: - Remove |padded| field - Introduce |state| field - |state| can be |KECCAK1600_STATE_ABSORB|, |KECCAK1600_STATE_SQUEEZE|, |KECCAK1600_STATE_FINAL| - |KECCAK1600_STATE_ABSORB| - allows incremental absorbs until the state is changed - |KECCAK1600_STATE_SQUEEZE| - allows incremental squeezes for |SHAKE_Squeeze| - |KECCAK1600_STATE_Final| - prevents from incremental squeezes via |SHAKE_Final| and prevents from consecutive calls to |SHA3_Final| (Final functions are single-shot functions). SHA3 vs SHAKE algorithms (APIs usage): >- SHA3 digest generation: SHA3_Init; SHA3_Update; SHA3_Final; >- SHAKE (single-shot-output) output generation: SHAKE_Init; SHAKE_Absorb; SHAKE_Final; >- SHAKE (incremental) output generation: SHAKE_Init; SHAKE_Absorb; SHAKE_Squeeze<sup>+</sup>; ### Call-outs: Service indicator is updated: - Inside SHA3 and SHAKE single shot APIs (as previously in AWS-LC); - Inside SHA3_Final (as previously in AWS-LC); - Inside SHAKE_Final (Single-Shot XOF Final output generation as previously in AWS-LC); - Inside SHAKE_Squeeze (Streaming XOF Squeezes output generation updates the service indicator after each extendable output update); All other algorithms that use SHA3/SHAKE APIs are updated: - ML-KEM (SHA3/SHAKE calls will be inlined later) - ML-DSA (SHAKE_Squeeze (incremental XOF output functionality) inside ML-DSA is never invoked with the KAT test vectors and gtests) ### Testing: _./crypto/crypto_test --gtest_filter="KeccakInternalTest.*"_ _./crypto/crypto_test --gtest_filter="SHA3Test.*"_ _./crypto/crypto_test --gtest_filter="SHAKETest.*"_ _./crypto/crypto_test --gtest_filter="All/PerKEMTest.*"_ _./crypto/crypto_test --gtest_filter="All/PQDSAParameterTest.*"_ By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license. --------- Co-authored-by: Jake Massimo <[email protected]> Co-authored-by: Will Childs-Klein <[email protected]> Co-authored-by: Justin W Smith <[email protected]> Co-authored-by: Shubham Mittal <[email protected]> Co-authored-by: Samuel Chiang <[email protected]> Co-authored-by: David Benjamin <[email protected]> Co-authored-by: Theo Buehler <[email protected]> Co-authored-by: Adam Langley <[email protected]> Co-authored-by: Brian Ledger <[email protected]> Co-authored-by: Nick Harper <[email protected]> Co-authored-by: Andrew Hopkins <[email protected]> Co-authored-by: torben-hansen <[email protected]> Co-authored-by: Sean McGrail <[email protected]> Co-authored-by: olivergillespie <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Issues:
Resolves Keccak1600_ Layer creation, part of #CryptoAlg-2810
Description of changes:
This PR introduces the lowest API layer for SHA3 and SHAKE new API design:
Call-outs:
Remove OPENSSL_EXPORT from some SHA3/SHAKE functions.
Testing:
./crypto/crypto_test --gtest_filter="KeccakInternalTest.*"
./crypto/crypto_test --gtest_filter="SHA3Test.*"
./crypto/crypto_test --gtest_filter="SHAKETest.*"
./crypto/crypto_test --gtest_filter="All/PerKEMTest.*"
./crypto/crypto_test --gtest_filter="All/PQDSAParameterTest.*"
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.